Python 虚拟环境使用¶

本文档说明 Quectel Pi M1/L1 上 Python 虚拟环境的基本使用方式。虚拟环境用于隔离项目依赖，避免第三方包影响系统 Python 环境。

环境确认¶

在开发板上先确认 Python 与系统环境：

python3 --version
cat /etc/os-release
command -v pip3 || echo "pip3 not installed"

项目	说明
系统	当前验证为 Debian GNU/Linux 13 (trixie)
Python	当前验证为 Python 3.13.5
pip3	当前镜像默认未检测到 pip3，按需安装

创建与启用¶

sudo apt update
sudo apt install -y python3-venv python3-pip
mkdir -p ~/projects/python-demo
cd ~/projects/python-demo
python3 -m venv .venv
source .venv/bin/activate

启用后可通过以下命令确认当前解释器和 pip 来自虚拟环境：

which python
which pip
python --version
pip --version

依赖管理¶

python -m pip install --upgrade pip
pip install <package_name>
pip freeze > requirements.txt
pip install -r requirements.txt

如项目需要 GPIO、串口或网络库，建议都安装在虚拟环境内。例如：

pip install pyserial requests python-periphery

退出环境¶

deactivate

注意事项¶

.venv 目录通常不纳入版本控制。
requirements.txt 建议随项目维护，便于多块开发板复现环境。
Debian 13 上不建议默认使用 --break-system-packages 修改系统 Python 环境。